Skip to content

refactor: convert command examples to @example attributes - #96

Merged
maxim-uvarov merged 5 commits into
mainfrom
refactor/convert-examples-to-attributes
Dec 15, 2025
Merged

refactor: convert command examples to @example attributes#96
maxim-uvarov merged 5 commits into
mainfrom
refactor/convert-examples-to-attributes

Conversation

@maxim-uvarov

@maxim-uvarov maxim-uvarov commented Dec 15, 2025

Copy link
Copy Markdown
Member

Summary

  • Convert all old-style # > comment examples to @example attributes in commands.nu
  • Add meaningful descriptions to all 21 @example attributes
  • Fix misleading comments to accurately describe function behavior
  • Fix bugs in existing @example attributes (wrong function names)

Changes

  • numd/commands.nu: Refactored examples and documentation

Test plan

  • All 46 unit tests pass
  • Integration tests pass
  • Module loads correctly

🤖 Generated with Claude Code

maxim-uvarov and others added 5 commits December 14, 2025 20:35
@maxim-uvarov
feat: add @examples
0e13c33
@maxim-uvarov
update readme to add examples
4f288fe
@claude @maxim-uvarov
refactor: convert command examples to @example attributes
bcad22d 
Convert all old-style comment examples (# > command) to @example attributes
in commands.nu. This improves testability and consistency across the codebase.

Changes:
- Fix bugs in existing @example attributes (wrong function names):
  * mark-code-block → code-block-marker
  * create-highlight-command → generate-highlight-print
- Convert 12 old-style comment examples to @example format:
  * convert-output-fences
  * convert-short-options
  * get-last-span (6 examples)
  * can-append-print (3 examples)
  * generate-inline-output-pipeline
  * generate-print-statement
  * generate-table-statement (2 examples)
  * wrap-in-try-catch
  * extract-fence-options
  * build-modified-path
- Remove untestable generate-timestamp example (dynamic output)

All examples now use consistent @example syntax for automated testing.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@claude @maxim-uvarov
docs: add descriptions to @example attributes
a739eba 
Added meaningful descriptions to all @example attributes in commands.nu,
replacing empty strings with explanatory text that describes what each
example demonstrates (e.g., "convert output fence to compact format",
"expand short option to long form", "pipeline ending with command").

Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@claude @maxim-uvarov
docs: fix misleading comments and synchronize documentation
acb8a82 
- Remove old debugging tip comment that looked like an example
- Fix process-code-block-content comment (clarify it generates code, doesn't execute)
- Improve generate-inline-output-pipeline comment for clarity
- Fix list syntax in extract-fence-options @example result (add comma separator)
- Add .claude/ to .gitignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@claude

claude Bot commented Dec 15, 2025

Copy link
Copy Markdown

Code Review: Convert Command Examples to @example Attributes

I've reviewed PR #96 and have the following feedback:

Positive Aspects

  1. Excellent Documentation Improvement: Converting from old-style comment examples to @example attributes is a significant improvement that makes the codebase more maintainable and aligns with Nushell best practices.

  2. Comprehensive Coverage: You've added meaningful @example attributes to 21 functions, which greatly improves discoverability through help commands.

  3. Accurate Descriptions: The example descriptions are clear and descriptive.

  4. Good Test Coverage: The PR mentions all 46 unit tests pass.

  5. Clean .gitignore Addition: Adding .claude/ to .gitignore is appropriate.

Issues and Concerns

Line 622-627: The get-last-span examples use --result with strings. Please verify these work correctly by running: help get-last-span

Line 673: The generate-inline-output-pipeline example has an extremely long --result string that's hard to read. Consider simplifying.

Line 689: The custom table width example modifies env.numd.table-width. Verify @example runs in isolated environments.

Line 560-562: The quote-for-print example has nested quotes that might be confusing. Consider adding an explanatory comment.

README.md Changes

The README updates are legitimate side effects of running numd run README.md:

  • Updated git tag from 0.1.21 to 0.2.2
  • Added new example output for numd run --help
  • Added new directories to z_examples listing
  • Minor whitespace fix

Security and Performance

No security concerns or performance impact identified - this is purely documentation.

Testing Recommendations

  1. Verify all @example attributes work correctly by testing help output for each modified function
  2. Run the full test suite: nu toolkit.nu testing --json
  3. Verify integration tests: nu toolkit.nu testing-integration

Summary

This is a high-quality refactoring that significantly improves documentation. Main concerns:

  1. Verify @example syntax is correct for all functions
  2. Test help output for all modified functions
  3. Consider simplifying the longest example strings

Recommendation: Approve after verification of the @example syntax via help commands.

Great work on this comprehensive documentation improvement!

@maxim-uvarov
maxim-uvarov merged commit 293f243 into main Dec 15, 2025
2 checks passed
@maxim-uvarov
maxim-uvarov deleted the refactor/convert-examples-to-attributes branch December 15, 2025 00:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@maxim-uvarov @claude